Skip to main content

標題：Ubuntu WSL 開發環境實戰指南
描述：實戰解決Ubuntu WSL環境中Windows與Linux工具共存的路徑衝突問題，包含Node.js/npm權限處理與環境隔離最佳實踐
最後更新：2025-06-29
版本：v1.0
作者：rj0217
來源：COVIA官方知識

Ubuntu WSL 開發環境實戰指南

前言​

本指南整理自實際開發過程中，對 Ubuntu WSL 環境管理常見問題的操作與驗證結果，特別針對 Windows 與 Linux 工具共存時的路徑衝突問題。所有內容基於實際操作經驗，無假設與推測，適合本地開發者與初學者作為環境管理參考。

1. WSL Ubuntu 環境的特殊性質​

路徑繼承問題​

  • WSL 預設會繼承 Windows 的 PATH 環境變數
  • 這會導致 Linux 環境中意外使用到 Windows 版本的工具
  • 典型問題：在 WSL 中執行 npm 實際上執行的是 Windows 版本

實際驗證方法​

# 檢查當前環境
uname -a
echo $WSL_DISTRO_NAME

# 檢查工具實際來源
which node
which npm

# 檢查 npm 配置路徑
npm config get prefix

2. Node.js/npm 環境衝突問題實戰​

問題現象​

  • which npm 顯示 /mnt/c/Program Files/nodejs/npm 或 /mnt/c/Users/User/AppData/Roaming/npm/npm
  • 安裝 Linux 專用套件時報錯「不支援 Windows」
  • npm config get prefix 顯示 Windows 路徑

解決步驟​

# 步驟1：暫時移除 Windows Node.js 路徑
export PATH=$(echo $PATH | tr ':' '\n' | grep -v "/mnt/c" | tr '\n' ':')

# 步驟2：驗證清理結果
which npm
which node

# 步驟3：安裝 Ubuntu 原生 Node.js
sudo apt update
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 步驟4：驗證安裝
which node  # 應顯示 /usr/bin/node
which npm   # 應顯示 /usr/bin/npm
node --version
npm --version

權限問題處理​

方案A：使用 sudo（快速但不推薦）​

sudo npm install -g [package-name]

方案B：設置用戶級全域目錄（推薦）​

# 在你的家目錄創建npm全域目錄
mkdir ~/.npm-global

# 設定npm使用新的目錄路徑
npm config set prefix '~/.npm-global'

# 將新路徑加入環境變數
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 現在可以安全安裝全域套件，無需sudo
npm install -g [package-name]

# 驗證安裝成功
which [package-name]

方案B優點：

  • 不需要 sudo 權限，更安全
  • 避免系統目錄權限衝突
  • 未來所有全域套件安裝都不會有權限問題
  • 設定一次，永久有效

永久解決方案​

# 在 ~/.bashrc 中加入路徑過濾
echo 'export PATH=$(echo $PATH | tr ":" "\n" | grep -v "/mnt/c" | tr "\n" ":")' >> ~/.bashrc

3. Ubuntu 中工具安裝的正確理解​

安裝路徑規則​

  • apt install 安裝的工具會出現在 /usr/bin/ 或 /bin/
  • 手動下載（如 curl 取得 .phar）並放置的工具，通常放在 /usr/local/bin/
  • npm install -g 安裝的工具：
    • 使用 sudo：預設在 /usr/local/lib/node_modules
    • 使用用戶級設定：在 ~/.npm-global/lib/node_modules

權限問題處理原則​

  • 推薦：設置用戶級全域目錄，避免權限問題
  • 備選：全域 npm 套件安裝需要 sudo 權限：sudo npm install -g [package]

4. 常用診斷指令​

查詢安裝的套件和工具​

# 查詢所有 apt 安裝的套件
apt list --installed

# 查詢 /usr/local/bin/ 手動安裝的執行檔
ls -lh /usr/local/bin/

# 查詢用戶級 npm 全域套件
ls -lh ~/.npm-global/bin/

# 搜尋專案資料夾內特定類型的執行檔
find /path/to/project -type f \( -iname "*.phar" -o -iname "*.sh" -o -iname "*.bin" \) 2>/dev/null

環境診斷​

# 查看完整 PATH
echo $PATH

# 查看特定工具的實際路徑
which [tool-name]

# 查看 WSL 發行版本
echo $WSL_DISTRO_NAME

# 檢查 npm 設定
npm config get prefix
npm config list

5. 實戰經驗要點​

已驗證的操作特性​

  • WSL 中的 uname -a 會顯示包含 "microsoft-standard-WSL2" 的資訊
  • which 命令能有效識別工具的實際來源路徑
  • PATH 環境變數的修改是臨時的，需要寫入 ~/.bashrc 才能永久生效
  • 使用 tr 命令進行路徑過濾是有效的解決方案
  • 用戶級 npm 全域目錄設定可有效避免權限問題

實際遇到的錯誤模式​

  • 「Claude Code is not supported on Windows」- 表示仍在使用 Windows 版工具
  • 「EACCES: permission denied」- Linux 環境中的權限問題
  • 「EPERM: operation not permitted」- Windows 路徑權限問題
  • 「Error: EACCES: permission denied, mkdir '/usr/lib/node_modules'」- npm 全域安裝權限問題

6. 特別注意事項​

環境隔離認知​

  • WSL Ubuntu 與 Windows 在檔案系統上是連通的，但工具環境需要明確區分
  • /mnt/c/ 路徑下的所有工具都是 Windows 版本
  • 本地安裝的工具無法自動影響 Docker container 中的環境，兩者完全隔離

路徑管理原則​

  • 在 PATH 中優先使用 Linux 原生工具路徑
  • 必要時完全移除 Windows 工具路徑避免衝突
  • 使用 which 命令確認實際使用的工具版本
  • 優先考慮用戶級安裝，避免系統權限衝突

7. 結論​

WSL Ubuntu 開發環境維護的核心原則：

  • 環境純淨性：明確區分 Windows 和 Linux 工具，避免路徑衝突
  • 路徑管理：主動管理 PATH 環境變數，確保使用正確版本的工具
  • 權限理解：了解 Linux 環境中的權限模型，優先使用用戶級安裝
  • 實際驗證：透過 which、uname 等命令確認環境狀態

本指南基於 Claude Code 安裝過程中的實際問題與解決經驗編寫，所有步驟均經過實際操作驗證。

文檔迭代紀錄​

協作夥伴戳記

  1. 向前待考察
  2. 2025/06/28 Claude 4 sonnet a13939d3-161d-4cb0-b4f2-dd2e36309892
  3. 2025/06/29 Claude 4 sonnet 56cbabc5-c668-4632-aa0f-dbd49cc9b598